[logs] Implement Journaling Payload to Disk for Network Outages#48143
[logs] Implement Journaling Payload to Disk for Network Outages#48143angel-ddog wants to merge 12 commits intomainfrom
Conversation
Go Package Import DifferencesBaseline: a58d244
|
Files inventory check summaryFile checks results against ancestor a58d2448: Results for datadog-agent_7.80.0~devel.git.27.5c0f26c.pipeline.108241515-1_amd64.deb:No change detected |
…gs-to-disk merged main into my branch
Static quality checks✅ Please find below the results from static quality gates Successful checksInfo
On-wire sizes (compressed)
|
Regression DetectorRegression Detector ResultsMetrics dashboard Baseline: 2a91625 Optimization Goals: ✅ No significant changes detected
|
| perf | experiment | goal | Δ mean % | Δ mean % CI | trials | links |
|---|---|---|---|---|---|---|
| ➖ | docker_containers_cpu | % cpu utilization | +0.79 | [-2.29, +3.88] | 1 | Logs |
Fine details of change detection per experiment
| perf | experiment | goal | Δ mean % | Δ mean % CI | trials | links |
|---|---|---|---|---|---|---|
| ➖ | otlp_ingest_logs | memory utilization | +1.67 | [+1.56, +1.77] | 1 | Logs |
| ➖ | ddot_metrics_sum_delta | memory utilization | +1.45 | [+1.27, +1.63] | 1 | Logs |
| ➖ | docker_containers_cpu | % cpu utilization | +0.79 | [-2.29, +3.88] | 1 | Logs |
| ➖ | quality_gate_logs | % cpu utilization | +0.78 | [-0.83, +2.40] | 1 | Logs bounds checks dashboard |
| ➖ | tcp_syslog_to_blackhole | ingress throughput | +0.64 | [+0.48, +0.79] | 1 | Logs |
| ➖ | ddot_logs | memory utilization | +0.55 | [+0.49, +0.60] | 1 | Logs |
| ➖ | docker_containers_memory | memory utilization | +0.52 | [+0.43, +0.61] | 1 | Logs |
| ➖ | quality_gate_metrics_logs | memory utilization | +0.43 | [+0.19, +0.67] | 1 | Logs bounds checks dashboard |
| ➖ | ddot_metrics_sum_cumulative | memory utilization | +0.42 | [+0.27, +0.57] | 1 | Logs |
| ➖ | uds_dogstatsd_20mb_12k_contexts_20_senders | memory utilization | +0.18 | [+0.12, +0.24] | 1 | Logs |
| ➖ | quality_gate_idle_all_features | memory utilization | +0.17 | [+0.14, +0.20] | 1 | Logs bounds checks dashboard |
| ➖ | file_tree | memory utilization | +0.14 | [+0.09, +0.20] | 1 | Logs |
| ➖ | ddot_metrics_sum_cumulativetodelta_exporter | memory utilization | +0.11 | [-0.11, +0.33] | 1 | Logs |
| ➖ | otlp_ingest_metrics | memory utilization | +0.09 | [-0.06, +0.24] | 1 | Logs |
| ➖ | file_to_blackhole_1000ms_latency | egress throughput | +0.08 | [-0.36, +0.52] | 1 | Logs |
| ➖ | ddot_metrics | memory utilization | +0.05 | [-0.14, +0.25] | 1 | Logs |
| ➖ | file_to_blackhole_0ms_latency | egress throughput | +0.05 | [-0.45, +0.56] | 1 | Logs |
| ➖ | uds_dogstatsd_to_api | ingress throughput | +0.00 | [-0.21, +0.21] | 1 | Logs |
| ➖ | tcp_dd_logs_filter_exclude | ingress throughput | -0.00 | [-0.11, +0.11] | 1 | Logs |
| ➖ | uds_dogstatsd_to_api_v3 | ingress throughput | -0.01 | [-0.21, +0.20] | 1 | Logs |
| ➖ | file_to_blackhole_100ms_latency | egress throughput | -0.04 | [-0.15, +0.08] | 1 | Logs |
| ➖ | file_to_blackhole_500ms_latency | egress throughput | -0.06 | [-0.46, +0.33] | 1 | Logs |
| ➖ | quality_gate_idle | memory utilization | -0.37 | [-0.42, -0.32] | 1 | Logs bounds checks dashboard |
Bounds Checks: ✅ Passed
| perf | experiment | bounds_check_name | replicates_passed | observed_value | links |
|---|---|---|---|---|---|
| ✅ | docker_containers_cpu | simple_check_run | 10/10 | 695 ≥ 26 | |
| ✅ | docker_containers_memory | memory_usage | 10/10 | 276.01MiB ≤ 370MiB | |
| ✅ | docker_containers_memory | simple_check_run | 10/10 | 682 ≥ 26 | |
| ✅ | file_to_blackhole_0ms_latency | memory_usage | 10/10 | 0.19GiB ≤ 1.20GiB | |
| ✅ | file_to_blackhole_0ms_latency | missed_bytes | 10/10 | 0B = 0B | |
| ✅ | file_to_blackhole_1000ms_latency | memory_usage | 10/10 | 0.24GiB ≤ 1.20GiB | |
| ✅ | file_to_blackhole_1000ms_latency | missed_bytes | 10/10 | 0B = 0B | |
| ✅ | file_to_blackhole_100ms_latency | memory_usage | 10/10 | 0.20GiB ≤ 1.20GiB | |
| ✅ | file_to_blackhole_100ms_latency | missed_bytes | 10/10 | 0B = 0B | |
| ✅ | file_to_blackhole_500ms_latency | memory_usage | 10/10 | 0.22GiB ≤ 1.20GiB | |
| ✅ | file_to_blackhole_500ms_latency | missed_bytes | 10/10 | 0B = 0B | |
| ✅ | quality_gate_idle | intake_connections | 10/10 | 4 = 4 | bounds checks dashboard |
| ✅ | quality_gate_idle | memory_usage | 10/10 | 174.79MiB ≤ 181MiB | bounds checks dashboard |
| ✅ | quality_gate_idle_all_features | intake_connections | 10/10 | 4 = 4 | bounds checks dashboard |
| ✅ | quality_gate_idle_all_features | memory_usage | 10/10 | 499.54MiB ≤ 550MiB | bounds checks dashboard |
| ✅ | quality_gate_logs | intake_connections | 10/10 | 4 ≤ 6 | bounds checks dashboard |
| ✅ | quality_gate_logs | memory_usage | 10/10 | 207.54MiB ≤ 220MiB | bounds checks dashboard |
| ✅ | quality_gate_logs | missed_bytes | 10/10 | 0B = 0B | bounds checks dashboard |
| ✅ | quality_gate_metrics_logs | cpu_usage | 10/10 | 345.99 ≤ 2000 | bounds checks dashboard |
| ✅ | quality_gate_metrics_logs | intake_connections | 10/10 | 4 ≤ 6 | bounds checks dashboard |
| ✅ | quality_gate_metrics_logs | memory_usage | 10/10 | 419.21MiB ≤ 475MiB | bounds checks dashboard |
| ✅ | quality_gate_metrics_logs | missed_bytes | 10/10 | 0B = 0B | bounds checks dashboard |
Explanation
Confidence level: 90.00%
Effect size tolerance: |Δ mean %| ≥ 5.00%
Performance changes are noted in the perf column of each table:
- ✅ = significantly better comparison variant performance
- ❌ = significantly worse comparison variant performance
- ➖ = no significant change in performance
A regression test is an A/B test of target performance in a repeatable rig, where "performance" is measured as "comparison variant minus baseline variant" for an optimization goal (e.g., ingress throughput). Due to intrinsic variability in measuring that goal, we can only estimate its mean value for each experiment; we report uncertainty in that value as a 90.00% confidence interval denoted "Δ mean % CI".
For each experiment, we decide whether a change in performance is a "regression" -- a change worth investigating further -- if all of the following criteria are true:
-
Its estimated |Δ mean %| ≥ 5.00%, indicating the change is big enough to merit a closer look.
-
Its 90.00% confidence interval "Δ mean % CI" does not contain zero, indicating that if our statistical model is accurate, there is at least a 90.00% chance there is a difference in performance between baseline and comparison variants.
-
Its configuration does not mark it "erratic".
CI Pass/Fail Decision
✅ Passed. All Quality Gates passed.
- quality_gate_idle, bounds check intake_connections: 10/10 replicas passed. Gate passed.
- quality_gate_idle, bounds check memory_usage: 10/10 replicas passed. Gate passed.
- quality_gate_logs, bounds check intake_connections: 10/10 replicas passed. Gate passed.
- quality_gate_logs, bounds check missed_bytes: 10/10 replicas passed. Gate passed.
- quality_gate_logs, bounds check memory_usage: 10/10 replicas passed. Gate passed.
- quality_gate_idle_all_features, bounds check intake_connections: 10/10 replicas passed. Gate passed.
- quality_gate_idle_all_features, bounds check memory_usage: 10/10 replicas passed. Gate passed.
- quality_gate_metrics_logs, bounds check memory_usage: 10/10 replicas passed. Gate passed.
- quality_gate_metrics_logs, bounds check intake_connections: 10/10 replicas passed. Gate passed.
- quality_gate_metrics_logs, bounds check cpu_usage: 10/10 replicas passed. Gate passed.
- quality_gate_metrics_logs, bounds check missed_bytes: 10/10 replicas passed. Gate passed.
…gs-to-disk merging into my branch
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4fd249d52a
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
… added message count bound to prevent OOM
…gs-to-disk merging with main
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 323a7e90ef
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
When a payload is stored to disk during an outage, notify the auditor so the tailer advances past those offsets and won't re-read them on restart. On shutdown, drain any payloads remaining in queue channels back to disk so they are not lost between enqueue and worker processing.
angel-ddog
left a comment
There was a problem hiding this comment.
Logs-agent architecture review
The diff introduces a disk-backed retry path inside the sender subsystem, but it changes the durable-progress contract in ways that conflict with the selected auditor and restart invariants. The main architectural risks are premature auditor advancement on local spool, replayed payloads no longer carrying enough origin identity to advance the auditor after actual delivery, and shutdown/restart sequencing that can strand in-flight payloads outside both the auditor and disk retry store.
Inline findings posted: 3
| // Try to save to disk instead of blocking the pipeline. | ||
| if err := s.retrier.Store(payload); err == nil { | ||
| // Update the auditor so the tailer advances past these | ||
| // offsets and won't re-read them on agent restart. |
There was a problem hiding this comment.
Worker advances the auditor when a payload is only spooled locally, not delivered to any reliable destination
When all reliable destinations are unavailable, the new path calls s.retrier.Store(payload) and then immediately pushes the same payload to reliableOutputChan, marking it as acknowledged for the auditor before any reliable destination has accepted it. The selected invariants require auditor progress to advance only after successful delivery to a reliable destination, and explicitly warn against treating buffered/intermediate storage as durable delivery. Local disk retry is an internal sender buffer, not a reliable destination acknowledgment. If the retry file later expires, is dropped for capacity, becomes unreadable, or replay never succeeds, the auditor may already have advanced past data that was never delivered upstream.
Context: invariants/auditor-delivery.md, invariants/sender-destination-semantics.md, architecture/pipeline-flow.md
Confidence: 0.98
| } | ||
|
|
||
| // diskRetrySource is a shared LogSource used for deserialized payloads. | ||
| // It provides the minimum non-nil structure needed so that deserialized payloads |
There was a problem hiding this comment.
Replayed payloads intentionally lose origin identity, so successful replay cannot update durable offsets anymore
DeserializePayload reconstructs MessageMetadata with a synthetic shared source and an empty Origin.Identifier, and the code comment states that the auditor will skip registry updates for such payloads. Combined with the new worker behavior, this means the only auditor advancement for disk-spooled payloads happens at spool time, not at actual destination success time. That breaks the sender/auditor boundary described in the selected pages: after restart, replayed payloads can be delivered successfully without any corresponding real auditor acknowledgment path tied to the original origin metadata. Architecturally this turns disk retry into a parallel persistence ledger outside the auditor, which the restart invariants do not recognize as the source of truth for durable progress.
Context: invariants/auditor-delivery.md, components/auditor.md, architecture/logs-agent-overview.md
Confidence: 0.95
| } | ||
|
|
||
| // Stop stops all sender workers | ||
| // Stop stops all sender workers and the disk retry replay loop. |
There was a problem hiding this comment.
Shutdown drains only queued payloads to disk and can drop payloads already dequeued by workers but not yet spooled or acknowledged
Sender.Stop() now stops the replay loop, then stops workers, then drains channel contents to disk. But workers remove payloads from queue channels before entering the reliable-send / disk-store loop. Any payload already dequeued into a worker when shutdown begins is not part of the post-stop queue drain, and there is no handoff ensuring it is either delivered, written to disk, or reflected in the auditor before the worker exits. The restart invariants require transient delivery components to stop cleanly before auditor flush, without dropped in-flight state. This stop ordering creates a concrete stranded-state window for in-flight payloads that are no longer in queues and not yet persisted anywhere durable.
Context: invariants/graceful-restart.md, components/restart-lifecycle.md, invariants/auditor-delivery.md
Confidence: 0.87
What does this PR do?
Adds an opt-in disk retry mechanism to the logs sender. During network outages, when the HTTP/TCP destination enters its retry loop and the sender buffer fills up, payloads that would otherwise be silently dropped are now written to disk. When connectivity recovers, the payloads are replayed in FIFO order back through the normal send path.
This feature is disabled by default. Setting
logs_config.disk_retry.max_size_bytesto a non-zero value enables it.Motivation
Epic
During network slowdowns or complete outages, the logs pipeline drops payloads. The destination enters an infinite retry loop on the current payload, the
DestinationSenderbuffer fills, and subsequent payloads are silently dropped. Customers lose log data with no recovery path. This change saves those payloads to disk and replays them when the network recovers.Changes
New package:
pkg/logs/sender/diskretry/serialization.go: Binary payload serialization/deserialization with magic number, version header, and corruption detectionretrier.go:Retrierinterface,DiskRetryManager(store, replay loop, disk capacity management, TTL expiry, startup reload), andnoopRetrierfor when disabledConfiguration
logs_config.disk_retry.max_size_bytes00= disabled.logs_config.disk_retry.path<run_path>/logs-retrylogs_config.disk_retry.max_disk_ratio0.80logs_config.disk_retry.file_ttl_days7Describe how you validated your changes
Manual QA:
disk-retry-qa-real.sh): confirmedduring-outagelogs appear in Log Explorer after recoveryScript:
Screenshots of Local Output (The replayed payloads appeared on the Logs Explorer as well):


This was my

datadog.yaml:Additional Notes
Originwith emptyIdentifierso the auditor safely skips registry updates without panicking